
=HTTPBridge Overlay=

HTTPBridge is an overlay that transforms the root request issued by the
[[doc:tpt:http:HTTPTransport|HTTPTransport]] into a normalized,
uniform ROC address space.
The overlay handles requests issued to the
[[doc:tpt:http:httpRequest|httpRequest:]] and
[[doc:tpt:http:httpResponse|httpResponse:]] 
spaces and maps them to the low-level underlying
HTTPRequest and HTTPResponse objects provided by the transport.
See the
[[doc:tpt:http:overview#Typical_Deployment_Pattern|overview]] 
for a diagram and general perspective.


{endpoint}jetty.HTTPBridge{/endpoint}


==Configuration==

The HTTPBridge '''should''' be configured to reside immediately after the HTTPTransport
as shown in the following example:

{xml}<rootspace>
	<endpoint>
		<prototype>HTTPTransport</prototype>
	</endpoint>
	<overlay>
		<prototype>HTTPBridge</prototype>
		<config>
			<rewrite>
				<match>http://.*?/(.*)</match>
				<to>res:/$1</to>
			</rewrite>
		</config>
		<space>
      <!-- Wrapped Space -->
    </space>
    </overlay>
    <fileset>
      <private/>
      <regex>res:/etc/HTTPServerConfig.xml</regex>
    </fileset>
    <import>
      <private/>
      <uri>urn:org:netkernel:ext:system</uri>
    </import>
    <import>
      <private/>
      <uri>urn:org:netkernel:ext:layer1</uri>
    </import>
    <import>
      <private/>
      <uri>urn:org:netkernel:tpt:http</uri>
    </import>
</rootspace>
{/xml}
 
and as depicted in the [[doc:tpt:http:overview#Typical_Deployment_Pattern|overview diagram]].

The overlay takes the 
{search}HTTPRequestResponseRepresentation{/search} 
object passed as the primary
argument in the HTTP transport's root request and dynamically
constructs an address space which it inserts into the request scope.
The overlay then issues a sub-request into its wrapped space.

The inserted dynamic space handles requests for the
<code>httpRequest:</code> and <code>httpResponse:</code> URI scheme,
mapping them to the information in the underlying HTTPRequest
and HTTPResponse objects.

Requests issued in the wrapped space for <code>httpRequest:</code> can
retrieve information ...
Requests issued with the SINK verb in the wrapped space for <code>httpResponse:</code> 
scheme
cause state to be accumulated and subsequently written to the
HTTPResponse output stream when the request completes processing.

If an exception is received for the sub-request - 
the bridge will make a request to the specified exceptionHandler interface passing 
the exception as 
the '''operand''' argument for processing.  
The response of the exception handler request is serialized to the HTTPResponse output stream 
and the appropriate HTTP response code is set.  

If a rewrite is specified in the config parameter the sub-request identifier will be
the transform of the incoming request by the rewrite regular expression.

==Instantiation==

To wrap an application space with the HTTPBridge overlay create the following overlay declaration

{xml}
<overlay>
	<prototype>HTTPBridge</prototype>
	<exceptionHandler>res:/introspect/exceptionhandler</exceptionHandler>
	<config>
		<rewrite>
			<match>http://.*?/(.*)</match>
			<to>res:/$1</to>
		</rewrite>
	</config>
	<space>
		Application Space
	</space>
</overlay>
{/xml}


Where the parameters are as follows:

*exceptionHandler - URI of an exception handler that will be called with an exception argument if the bridge receives an exception. The exception handler must return a serializable response that the bridge will write to the HTTPResponse.
*config - an optional rewrite statement which is applied to the incoming request before the overlay issues its request into the application space.  Here it is used to remove the host name and URI scheme of the request to move the request into the uniform res: address space.
*space - as with all overlay declaration the space will receive all requests from the overlay.

==Operation==

When an HTTP root request is received

==Additional Discussion==




